Ian & Stuart's Australian Mac: Not for Sale

home *** CD-ROM | disk | FTP | other *** search

/ Ian & Stuart's Australian Mac: Not for Sale / Another.not.for.sale (Australia).iso / fade into you / being there / Issues & Ideas / SGML / Kimber-on-HyQ-1.1 < prev next >

Wrap

Text File | 1992-07-21 | 91KB | 2,798 lines

Sender: drmacro@vnet.ibm.com Message-Id: <9308030227.AA01688@relay1.UU.NET> Date: Mon, 2 Aug 93 22:27:36 EDT From: "W. Eliot Kimber" <drmacro@vnet.ibm.com> To: srn@techno.com HYTIME AND SGML UNDERSTANDING THE HYTIME HYQ QUERY LANGUAGE 1.1 August 2, 1993 W. Eliot Kimber VNET: DRMACRO at RALVM13 Internet: drmacro@vnet.ibm.com IBMMAIL: USIB2DK9@IBMMAIL Phone: (919) 254-5160 Mail: IBM Corporation 4205 S. Miami Blvd. Research Triangle Park, NC 27709 USA Mail stop: E14/B500 IBM Internal Use Only FIRST EDITION You may copy this document freely as long as this copyright notice is included without modification. (C) COPYRIGHT INTERNATIONAL BUSINESS MACHINES CORPORATION 1993. ALL RIGHTS RESERVED. Note to U.S. Government Users -- Documentation related to restricted rights -- Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp. ------------------------------------------------------------------------------ About this Document This document is intended to provide a brief, tutorial introduction to the HyQ language. It is assumed you have a working knowledge of SGML and have a copy of the HyTime standard, ISO 10744 at hand, although it does not assume you have more than a passing familiarity with HyTime. ----------- Conventions Whenever a term defined in either the SGML standard, ISO 8879, or the HyTime standard is used for the first time, it is highlighted like so: SPECIALIZED TERM. These terms represent the specialized jargon of SGML and HyTime. They have precise meanings that may be different from their more common usage. The HyQ functions are defined using "railroad track" syntax diagrams similar to the sort used in Pascal documentation. To read a syntax diagram, start at the left and follow the tracks, collecting characters as you go, including any blanks. A typical diagram looks like this: .- DEFAULT-. >>--fubar(variable--.-----------.--.- CHOICE1-.--+----------+--------> '- OPTIONAL-' '- CHOICE2-' |- CHOICE1-| '- CHOICE2-' <-----------< >--| Fragment Reference |--- REPEATABLE----------------------------->< Fragment references are references to other syntax diagrams presented elsewhere. ----------------------------- Assumptions Made for Examples To keep the examples as brief as possible, not all the aspects of HyTime that you would have in a real application are shown. For example, elements that are defined for the purpose of the examples are not explicitly defined anywhere. All elements used in examples that are HyTime elements are presented as is. Elements that are made-up application-specific elements for the purposes of the examples are always indicated as being made-up. ------------------------ Accuracy of the Examples I have made every effort to check the examples against the HyTime standard. Wherever I have had a question as to the proper specification or use of a HyTime or HyQ construct I have asked for clarification from Charles Goldfarb, the editor of the HyTime standard, or Steve DeRose, one of the principle architects of the HyQ language itself. Any inaccuracies are mine. If you find any inaccuracies, or have any other comments on this document, please send a note to the address shown on the title page. ------------------------------------------------------------------------------ Acknowledgements Special thanks to the following people who have provided invaluable assistance in insuring the quality and accuracy of this information: o Victoria Newcomb o Neill Kipp o Steve DeRose o Michael Sperberg-McQueen o Wayne Wohler o David Cattarin ------------------------------------------------------------------------------ Changes to This Document | Changes to the latest version are marked with a vertical bar in the | margin as this paragraph is. Changes for version 1.1, August 2, 1993: o Fixed several errors in detail in various examples o Fixed the TESTDOC example by adding missing ID= values and explicitly ending all elements. o Added to the description of property locations and fixed all the Proploc() examples to match ISO 10744. o Fixed technical errors in the description of Dataloc(). o Clarified the description of Listloc(). ------------------------------------------------------------------------------ Introduction to HyTime and HyQ HyTime is an ISO standard that defines an architecture for creating hypertext and hypermedia applications. HyTime primarily addresses the problem of hyperlinking as a problem of addressing, in other words, locating objects in space or time. A key aspect of addressing is the use of queries to find things based on their properties. HyTime is an SGML application, which means that it is designed using SGML as the notation language and defines a number of functions related directly to SGML constructs. The HyTime standard defines the HyQ query language as the recommended notation to use for queries within a HyTime context. HyQ is designed to directly reflect HyTime constructs and addressing methods and is therefore optimized for use within HyTime applications. HyQ is not tied to any particular retrieval or search engine and therefore represents an interchange language for queries that would then be interpreted into concrete queries using proprietary query languages or mechanisms. This document is an introduction to the HyQ language. It shows how the HyQ language is structured and how you use it to construct various types of queries. It also provides an overview of the various HyTime addressing methods, as those are also used by HyQ. The last part of this document is a HyQ reference, containing a reference page for each HyQ function. This reference is intended to supplement the HyQ definition in the HyTime standard itself by providing examples and explanations of typical uses of each function. ------------------------------------------------------------------------------ HyTime Addressing and HyQ HyTime is about addressing. HyTime works with objects in finite coordinate spaces and objects within trees. --------------------- Coordinate Addressing Coordinate spaces are always defined in terms of quanta, in other words, non-divisible integer units. A one-dimensional coordinate space can be represented as a number line, like so: 1 2 3 4 5 6 7 8 | | | | | | | | | |---+---+---+---+---+---+---+---+ | | | | | | | | | This coordinate space consists of eight quanta. A two-dimensional coordinate space can be represented by a matrix: +-----------------------------------------------+ 5 | | | | | | | | | | | | | |---+---+---+---+---+---+---+---+---+---+---+---| 4 | | | | | | | | | | | | | |---+---+---+---+---+---+---+---+---+---+---+---| 3 | | | | | | | | | | | | | |---+---+---+---+---+---+---+---+---+---+---+---| 2 | | | | | | | | | | | | | |---+---+---+---+---+---+---+---+---+---+---+---| 1 | | | | | | | | | | | | | +-----------------------------------------------+ 1 2 3 4 5 6 7 8 9 10 11 12 Locations within coordinate spaces are represented by sets of DIMENSION SPECIFICATIONS. A dimension specification, or dimspec, is made up of two AXIS MARKERS, which are signed, non-zero integers. The first axis marker locates the starting quantum and the second axis marker defines the extent (number of quanta) of the address. The start is the start of the location and is normally the quantum number of the starting position. The extent is the number of quanta to move to define the length of the location on that axis. Counting is always done in the direction of the end of the finite coordinate space (except in one special case explained below). For example, the dimension specification '1 1' indicates the first quantum, '2 1' locates the second quantum, and '2 3' locates the second through fourth quanta (start at quantum 2 and move over three quanta). A single dimension specification locates within a one-dimensional coordinate space. When multiple axis marker pairs are used to address multiple locations as though they were a single object, they are contained in a DIMENSION LIST or dimlist. The marker pairs within a given dimension list all apply to a single axis in the addressible range. You can think of a dimspec as a special case of dimlist that only addresses a single location. | Dimension specifications are used to locate within a single dimension | or along a single axis. but to locate within a multi-dimensional | space, you create an extent, which contains a dimlist for each axis in | the coordinate space and defines the extent of the region of the | finite coordinate space being located.(1) To locate the first quantum | in a matrix, you would specify '1 1' '1 1'. To locate a rectangular | area two quanta by three quanta, you would specify the extent like so: | <extent> | <dimlist>1 2</><dimlist>1 3</> | </extent> | which would look like so: +---------------------------------------------------+ 6 | | | | | | | | | | | | | | |---+---+---+---+---+---+---+---+---+---+---+---+---| 5 | | | | | | | | | | | | | | |---+---+---+---+---+---+---+---+---+---+---+---+---| 4 | | | | | | | | | | | | | | |---+---+---+---+---+---+---+---+---+---+---+---+---| 3 | x | x | | | | | | | | | | | | |---+---+---+---+---+---+---+---+---+---+---+---+---| 2 | x | x | | | | | | | | | | | | |---+---+---+---+---+---+---+---+---+---+---+---+---| 1 | x | x | | | | | | | | | | | | +---------------------------------------------------+ 1 2 3 4 5 6 7 8 9 10 11 12 13 extent="(1 2) (1 3)" The area within a given coordinate space that a dimension specification is actually addressing is called the ADDRESSABLE RANGE. The addressable range always has well-defined boundaries, in other words, a start and an end. Knowing where the end of the addressable range is lets you specify locations relative to the end of the range as well as relative to the start of the range. The start and extent values have special meanings when a minus sign is used with them. When the start quantum is negative, it indicates that counting starts at the end of the addressable range rather than at the beginning. For example, the dimspec '-1 1' locates the last quantum in the range, | while '-2 2' locates the last two quanta in the range. When the extent value is negative, it indicates that the extent is from the end of the range, not the starting quanta. For example, the dimspec '1 -1' locates the entire range, while '2 -1 'locates all but the first quanta in the range. '2 -2' would locate all but the first and last quanta in the range. When the first marker is negative and the extent is negative, it indicates that the direction of counting is from the end of the range, but starting from the second marker, not the end of the range. In other words, the first marker indicates the number of quanta to move toward the start of the range, starting at the position indicated by the second marker. For example, in a range of ten quanta, the dimspec '-3 -2' means the 7th through 9th quanta inclusive. In other words, locate the second quanta from the end of the marker (quantum nine) then locate the third quanta in the direction of the start of the range (quantum seven): Dimspec="-3 -2" +--- Second quanta from end (-2) V 1 2 3 4 5 6 7 8 9 10 | | | | | | | x | x | x | | |---+---+---+---+---+---+---+---+---+---| | | | | | | | A | | | | +---- Third quanta from second marker (-3) All this does is treat the end of the range as though it were the start and the first marker as though it were the extent and the second marker as though it were the starting quantum. | Another way to think of this is that when the signs of both markers | are the same, then the first indicates a start location and the second | indicates the number of quanta to move to the right (moving right -2 | is the same as moving left 2). ---------------------------- Nodelist and Tree Addressing HyTime also provides location mechanisms for locating objects within trees. In HyTime terms, a tree represents a hierarchical collection of NODES, where a node is to a tree what a quantum is to a coordinate space: simply a way of defining where something is located in a tree. Nodes can also be organized into lists, called NODE LISTS. Nodes have the special property that they can be the roots of trees. The typical use of tree locations in HyTime applications is to locate elements within SGML documents, as SGML documents are always hierarchical structures of elements and are therefore naturally represented as trees(2). Other types of data can be addressed as trees or nodelists by providing notation handlers for those data notations that can translate node and tree addresses into real addresses for that data type. For example, a notation handler for PostScript data could allow addressing of pages in a PostScript listing as nodes in a node list. It is up to the implementer of a given HyTime system to provide this sort of functionality. Nodes can thus be organized or viewed as members of node lists or trees. Nodes can be located by any one of the following location mechanisms: o Tree location address o list location address o path location address o relative location address Node and tree locations are primarily used to locate elements within SGML documents, but they can be used to locate within any type of data that is represented as a tree or node list. tree location address Locates a node in a tree by selecting an ancestor node at each level | of the tree. E.g., the location '1 2 3 1' selects the first child of the third child of the second child of the root. Note that nodes are counted in left-list preorder, e.g., top to bottom, left to right. | Note also that the root node must always be identified in the tree | location. list location address Address one or more nodes within a node list. The list location is a coordinate location where the coordinate space is a list of nodes. For example, the list location '2 3' locates the second through fourth nodes in a node list. path location address Locates one or more "paths" down a tree. The path location address is a coordinate location that addresses a tree as though it were a matrix in which the rows are the levels of the tree and the matrix columns are the paths down the tree. Consider the following tree: +---+ | A | +---+ +----------+------------+ | | | +---+ +---+ +---+ | B | | C | | D | +---+ +---+ +---+ +-------+ | +-------+ | | | | | +---+ +---+ +---+ +---+ +---+ | E | | F | | G | | H | | I | +---+ +---+ +---+ +---+ +---+ | +---+ | J | +---+ All the paths through the tree can be represented as a matrix where each column is a path from the root to a leaf: Paths 1 2 3 4 5 --------- Level 1: A A A A A Level 2: B B C D D Level 3: E F G H I Level 4: - J - - - Any single path can be located by specifying the column and then the number of nodes within the column to select. For example, the path from A to J would be '2 1 1 -1'. The first dimension, '2 1', locates the second column. The second dimension locates the entire length of the column. relative location address Addresses nodes in a tree based on their genealogical relationship to another node in the tree. You locate the position of the node the other nodes are relatives of, specify the general relationship that the target nodes have (e.g., child, ancestor, elder sibling, younger sibling, descendant). The relationship specification effectively defines the node list or pathlist within which the target nodes are located. You then specify a coordinate location locating the actual nodes. For example, to locate the third child of the root of a document you would specify this relative location address: <relloc id=sample-relloc relation=children>3 1</relloc> The root of the relative location is, by default, the root of the document. The relation 'children' defines the target domain as the node list consisting of all direct children of the root. The dimension specification '3 1' locates the third node within the node list, effectively locating the third child of the root. ------------------ Semantic Locations Semantic locations provide means of locating aspects of objects that are unique to their semantic roles, as opposed to their structural roles. Semantic location methods are: o Property locations (proploc). Proploc locates values of object properties, such as attribute values and generic identifiers. Non-SGML data notations can have properties defined for them using the HyTime property definition constructs. o Notation-specific locations (notloc). Notloc locates into data in a given notation using addressing methods specific to that notation, as opposed to using normal HyTime addressing that is interpreted by a notation processor that understands HyTime addressing. o Bibliographic locations (bibloc). Bibloc locates elements that are not directly addressable by the system, normally references to real objects, such as printed books, people, and the like. Proploc is the semantic location method used most often. Notloc is a sort of "escape" that allows addressing into data notations for which generalized HyTime support has not been provided. Property Location Addressing SGML elements have properties as defined by ISO 8879, e.g., the generic identifier and any declared attributes. In addition, application designers may define other properties for elements or for other data types. Property definition is done in HyTime using the HyTime property definition element form, defined in Annex A.2. You can define new properties and given them names by which they can be referred to from a proploc. To refer to element attributes within a proploc, you specify the property name 'ATTVAL' followed by the attribute name, separated by a null end tag (NET) delimiter (normally a solidus ([], like so: <HyQ> proploc(DOMROOT ATTVAL[SECURITY]) </HyQ> | The string ATTVAL[SECURITY]' is a qualified property name (qpn), made | up of the following parts:(3) 'ATTVAL' identifies the property itself, | in this case, an attribute value. '[SECURITY]' defines the specifier | for the property, in this case, the attribute name. A specifier | defines the data that allows for selection among properties of the | same type. In this example, the attribute name is the specifier for | selecting among the values of the various attributes of the element | being located. Without the specifier, the proploc() would return the | values of all the attributes. The syntax of qualified property names | of this form is defined in section A.1.3 Useful Hylex Types in ISO | 10744. | All property names are specified relative to a defined set of | properties, called a property set. For all standard SGML and HyTime | constructs, these properties are part of the standard property sets | used by default. However, you can specify the property set name | explicitly, like so: | <HyQ> | proploc(DOMROOT HTsem1+ATTVAL[SECURITY]) | </HyQ> | 'HTsem1' identifies the property set in which the named property is | defined. The standard property sets are defined in section A.2.1 of | ISO 10744. Thus the proploc() function in this example returns the value of the attribute. If the actual markup is: <mydoc security="iuo"> Then the query would return the value 'iuo'. The special keyword GI refers to the generic identifier property of the element. Applied to the markup above, the following query returns 'mydoc'.(4) <HyQ> proploc(DOMROOT GI) </HyQ> | If you are going to need to specify the same long qualified property | name many times, it may be convenient to define a property name | synonym for it. For example, the value of the ID= attribute is a | property that is use frequently, so it would make sense to define a | synonym for it, something like this: | <HyPD psn=myprops syn pn=idatt> | HTsem1+ATTVAL[ID] | </HyPD> | The property set name 'myprops' must be declared as a notation and | represents a set of properties defined locally (for example, within | the metadtd for an application architecture or the concrete DTD of an | SGML application). Having defined this synonym, you can now use the | property name directly and simply: | proploc(CAND myprops+idatt) | You can also specify property set names on elements that contain the | query using the qpnpsn= attribute (defined as one of the all-qual | qualifying name attributes in section 6.7.3 of ISO 10744). This | allows you to specify the names of property sets to be searched to | find the definitions of various property names, eliminating the need | to explicitly specify property set names. For example, the above | proploc() could be changed to this, within the context of a HyQ | element: | <HyQ qpnpsn=myprops> | proploc(CAND idatt) | </hyq> Notation Location Addressing Notation locations are location address specifications unique to a particular data notation, rather than being standard HyTime dimension references or queries. Notation locations must be used to address into data notations for which a HyTime-knowledgeable notation processor is not available. The main problem with notation locations is that they are directly tied a specific notation and are thus not very interchangeable. In a pure HyTime system, for each supported notation there would be at least one notation processor that would accept standard HyTime address (dimension specifications or data locations, for example) and would know how to transform the HyTime specification into real locations in the specific data notation. For example, say you wanted to address words in text regardless of the format that text is stored in, because it could be in any one of several proprietary formats. If each format has a HyTime notation processor available, you could use a simple data location address with a defined quanta of WORD without having to worry about how to actually find words in the actual data, because the notation processor would handle that transparently. However, if there was a format for which there was no HyTime-knowledgeable notation processor, to address words, you might have to specify the address in the specific notation. For text in a given word processor format, that might mean specifying the editor macros that would return what you want as the address, say something like this: <notloc notation=PandaWord> @macro(find_mark("fubar"), start_select(), move_word(3), end_select(), copy(), return(clipboard())) </notloc> Compare with the equivalent dataloc: <dataloc locsrc=fubar quantum=word>1 3</dataloc> HyQ does not provide a notation location function, but you could use a notloc indirectly by using the object-of function (oo()) to refer to the notloc element that addresses the objects you need. Bibliographic Location Addressing Bibliographic locations address objects that are not directly addressable by the computer system or application. For example, you could create a "hyperlink" to a document that only exists in print by using a bibliographic location giving its Library of Congress number. Bibliographic locations cannot be used as location sources, so they cannot be used within HyQ queries. ------------------------------------------------------------------------------ Getting Started with HyQ HyQ is a language for use with HyTime location addressing facilities. It represents a sort of "API" by which computer systems can interact with HyTime systems using HyTime location mechanisms. For example, a database retrieval system might use HyQ queries to locate data within an SGML database, or an online presentation system might use HyQ queries to interact with other online systems through a HyTime engine. HyQ queries can also be used within HyTime location elements that allow queries, such as the NMQuery element used within named address location elements (nameloc). The HyQ language is defined within Annex A of the HyTime Standard. ---------- HyQ Basics HyQ operates on and returns node lists. The set of nodes against which the query is performed is called the QUERY DOMAIN. This query domain is defined by specifying the node that forms the root of the tree containing the target nodes. For example, to locate elements within an SGML document, you would specify the root node of the document (the DOCUMENT ELEMENT) as the domain root. The HyQ language itself is a lisp-like language where queries are specified by nesting HyQ functions within other functions. A typical HyQ query is: <HyQ qdomain=mydocument> | Select(DOMTREE EQ(Proploc(CAND GI) "CHAPTER")) </HyQ> The HyQ element contains the query itself; the qdomain= attribute identifies the query domain (the root node of the tree against which the query is performed). In this example, pointing to the document element for an document called mydocument. By default, the query domain for a HyQ query is the current SGML document. Function parameters are blank-delimited, with literal strings enclosed in single or double quotes. A query can include variable arguments that are passed in as values of the ARGS= attribute of the HyQ element. The following keywords have special meaning within a HyQ query: DOMROOT Refers to the root node list of the query. DOMTREE Refers to the tree of nodes rooted at DOMROOT. CAND Refers to the candidate under test in a select() function. The select() function takes a node list and an assertion and applies the assertion to each member of the node list in turn. The keyword CAND can be used within the assertion to refer to the current candidate node. The select() function returns a node list containing the candidates for which the assertion was true. For example, in the HyQ query shown above, the select's input node list is defined as the DOMTREE, in other words, all nodes in the query domain. The assertion is asking if the candidate's GI value (tag name) is equal to the value 'Chapter'. The select then returns a nodelist containing each node that does have a GI of 'Chapter'. In the context of this query, the nodes are SGML elements. The essential question in this query is "is the GI equal to 'Chapter'?" To answer this question, you must first find out for each node in the query domain what its GI is, thus the proploc() function, which returns the value of a property, in this case, the GI property: "Proploc(CAND GI)". Remember that the CAND keyword refers to the current candidate node from the node list specified for the select() function. Having the GI for each candidate node, you now compare it to the literal string 'Chapter' using the EQ() function. The EQ() function compares the first parameter and the second parameter and returns TRUE if they are equal. This true or false value is then used by the select() function to determine which of the nodes in the input node list to return. To test this query, try applying it to the following sample document: <testdoc id=a> <body id=b> <Chapter id=intro-chap><title id=e>Introduction</title> <p id=c>Introduction</p> <Chapter id=complex><title id=f>Complex Stuff</title> <p id=d>This is about complex stuff.</p> </body> </testdoc> The outermost function is: select(DOMTREE assertion) The keyword DOMTREE represents the node list of all elements in the document, rooted at the document element (<testdoc> in this case). For this exercise, represent this node list by listing the IDs of the elements: | "a b intro-chap e c complex f d" The assertion is then applied to each member of the node list. To work the assertion, start from the inside out. The lowest level function returns the GI of each candidate node using the proploc() function: proploc(CAND GI) For the first node in node list (element with ID=a), proploc returns 'testdoc'. The next layer is the EQ() function to see if the GI is equal to the string 'Chapter': EQ(CAND proploc(CAND GI) "CHAPTER") For the first candidate (taken from the node list supplied for the select), the element with ID=a, the result of the EQ is FALSE because 'testdoc' is not equal to 'Chapter'. Thus, the candidate is not put into the node list returned by the select() function. Repeat the above steps for each node in the node list. The node list returned by the select() should be: "intro-chap complex" Note that for this example you've used the IDs of the elements to represent the node list. In a real system, the node list would actually contain pointers to the SGML elements themselves, rather than a literal list of element IDs. This is an important distinction to keep in mind because a node list can be a set of literal values. For example, consider this query: <HyQ> proploc(DOMTREE ATTVAL[ID]) </HyQ> This query uses the proploc() function to return for each node in DOMTREE the value of the ID= attribute, resulting in a node list that is a set of literal ID values. It is important to keep in mind the type of data each HyQ function | returns. HyQ functions return one of three types of data: Boolean | values (true or false), node lists, or literal data. All the | assertion functions return Boolean values. Dataloc() and proploc() | return literal data, and all other functions return node lists. Note | that literal data strings can be the nodes in a node list. For | example, a proploc() that operates against each of the nodes in a node | list will itself return a node list of literal values, one for the | property value for each node in the input node list. These are simple examples, but they demonstrate the basic approach to using HyQ to locate objects and get information about objects. ---------------------- Defining HyQ Functions You can define HyQ functions to capture common queries that can be re-used. To create a HyQ function, you create a HyQ element with an FN= attribute. The FN= attribute defines the function name for this function: <HyQ fn=HasGI> Select(DOMTREE EQ(proploc(CAND GI) %1)) </HyQ> The '%1' is a variable parameter. You use a function one of two ways. You can refer to a function directly from the HyQ element by using the UseFN= and Args= attributes to refer to a previously-defined function: <HyQ usefn=HasGI args="P"> When you specify the UseFN= attribute, the HyQ element is empty and cannot have an end tag specified. You can also use a function within another HyQ query using the UseQ() function to name the function and pass the arguments: <HyQ> UseQ(HasGI "P") </HyQ> The parameters are substituted in the order specified on the Args= attribute or in the UseQ() function. Parameters for which no value was specified are empty. ------------------------------------------------------------------------------ The HyQ Primitive Operations This section defines each of the HyQ primitive functions. The description of each function contains a formal definition of its parameters, a general description of what the function does, and some examples of how it might be used. This information is taken directly from Annex A of ISO 10744. The functions are in alphabetical order by function name. The following entries group the various related funcions together: NODE Lists the constructs that are valid wherever a node is valid. NODE LIST Lists the constructs that are valid wherever a node list is valid. ASSERTION Lists the functions that provide Boolean operations or logical comparisons. NLOPS Lists functions that operate against node lists NLDEFS Lists functions that define or create node lists ------------------------------------------------------------------------------ ah() User-defined assertion handler Syntax >>--ah(idref -| Node List |-)--------------------------------------->< idref Refers to the object that implements the assertion. NODE LIST The node list contains the operands of the assertion. The meaning of the operands is defined by the assertion implementation. Purpose The assertion handler function allows you to define and implement assertions that the base HyQ definition does not provide. Examples In the following example, the ID reference is to an application-defined element that contains a Rexx function that implements the assertion. <assertion-function id=compare-objects> /* Rexx Function */ Compare_Objects: procedure arg objectname fieldname comparison_value . interpret "IF "objectname"."fieldname "== comparison_value ", "THEN return(1) ELSE return(0)" return(0) /* just in case */ </assertion-function> . . . <HyQ> select(DOMTREE ah(compare-objects ("mystem" "0owner" "DRMACRO"))) </HyQ> In this example, the DOMTREE would be defined to be the set of Rexx stemmed variables the assertion is applied against. The node list of parameters for the Compare_Objects() Rexx function results in the following IF statement being executed as a result of applying the interpret operation: IF mystem.0owner == comparison_value THEN return(1) ELSE return(0) The Rexx variable comparison_value has the value 'DRMACRO' in this case. ------------------------------------------------------------------------------ and() Test Boolean AND Syntax <---------------< >>--and(---| Assertion |---)---------------------------------------->< ASSERTION Any of the HyQ assertion functions. Purpose And() returns TRUE only when all assertions return TRUE. Examples In this example, And() is used to see if two properties have a certain combination of values: <HyQ> select(DOMTREE AND(EQ(proploc(CAND ATTVAL[STATUS]) "CHANGED") EQ(proploc(CAND ATTVAL[VERSION]) "V1R2"))) </HyQ> The AND() in this case contains two EQ() assertions. Each EQ() compares the value of an attribute with a string and returns TRUE or FALSE based on the match. The AND() function will return TRUE if both EQ() functions return TRUE, otherwise it will return FALSE. Thus the select() function will return a node list containing each element in DOMTREE for which STATUS equals 'CHANGED' and VERSION equals 'V1R2'. ------------------------------------------------------------------------------ assert() Test assertion Syntax >>--assert(-.-TRUE----------.-)------------------------------------->< |-FALSE---------| '-| Assertion |-' TRUE FALSE ASSERTION The Boolean value to assert (TRUE or FALSE) or an assertion function that will return either TRUE or FALSE. Purpose Returns TRUE or FALSE. Examples In this trivial example, the Assert() function causes the select() function to always return the input node list: <HyQ> select(DOMTREE assert(TRUE)) </HyQ> ------------------------------------------------------------------------------ assertion Functions that return TRUE or FALSE Syntax ASSERTION: |--assert(-.-| assert() |--.-)---------------------------------------| |-| ah() |------| |-| compare() |-| |-| ordered() |-| |-| and() |-----| |-| or() |------| |-| not() |-----| |-| forall() |--| '-| exists |----' Purpose All the assertion functions return TRUE or FALSE. Use assertion functions within select() or within any function that takes an assertion as an argument. Note that exists is not a function, but is merely a property of node lists such that when a node or node list occurs where an assertion is expected, the node evaluates to TRUE if it is non-empty, FALSE if it is empty. | For example, the following And() function returns TRUE because | assign() always returns true and the node list referenced by nlref() | is not empty (having been assigned a non-null value): | <HyQ> | and(assign(notempty ("has a value")) | nlref(notempty) | ) | </HyQ> ------------------------------------------------------------------------------ assign() Assign a local name to a node list Syntax >>--assign(name -| Node List |-)------------------------------------>< name The symbolic name to be assigned to the node list. The name is available to the entire HyQ query body and any nested queries. The name cannot be re-defined within the scope of a single query. NODE LIST The node list to which the name is being assigned. Purpose Use Assign() to assign a symbolic name to a node list as a convenience in specifying other parts of a query. Use the nlref() function to use a node list name created with assign(). Examples In this example, assign() is used to assign a name to the node list representing the elder siblings of a node: <HyQ> ASSIGN(ElderSiblings relloc(DOMTREE oo(an-element) esib (1 -1))) select(nlref(ElderSiblings) EQ(proploc(CAND GI) "P")) </HyQ> The relloc() function defines the node list by locating all elder siblings of the element with the ID of 'an-element'. This named node list is then used in the select() function to return the list of elements within the list of elder siblings that have a GI of 'P'. ------------------------------------------------------------------------------ count() Return number of quanta in range Syntax >>--count(-| Node List |--.----------.-)---------------------------->< '- quantum-' Purpose Examples This example extends the example for assign by using Count() to return the number of elder P siblings of the element with the ID 'an-element': <HyQ> assign(ElderSiblings relloc(DOMTREE oo(an-element) esib (1 -1))) COUNT(select(nlref(ElderSiblings) EQ(proploc(CAND GI) "P"))) </HyQ> ------------------------------------------------------------------------------ compare() Tests ordering of nodes in lists Syntax .- STR--. <- --------------------< >>--compare(--.-EQ-.--(--+-------+----.-| Node |------.--)---------->< |-NE-| |- NORM-| '-| Node List |-' |-LT-| |- WORD-| |-LE-| |- NAME-| |-GT-| |- SINT-| |-GE-| |- DATE-| |-SS-| |- TIME-| |-NS-| '- UTC--' |-ST-| |-SE-| |-BT-| |-BE-| |-HO-| |-HE-| |-IH-| '-IE-' comparison operator Defines the type of comparison to be performed. COMPARISON OPERATORS The following comparison operators can be used to specify the type of comparison to perform against the members of the node list: EQ All members are equal to each other. NE AT least two operands are not equal. LT Each operand is less than its successor. LE Each operand is less than or equal to its successor. GT Each operand is greater than its successor. GE Each operand is greater than or equal to its successor. SS All operands are the same size (same number of quanta) NS At least two operands are not the same size. ST Each operand is smaller (shorter) than its successor. SE Each operand is smaller (shorter) than or equal to its successor. BT Each operand is bigger (longer) than its successor. BE Each operand is bigger (longer) than or equal to its successor. HO Each operand holds its successor (proper superstring) HE Each operand holds or equals its successor (superstring) IH Each operand is held by its successor (proper substring) IE Each operand is held by or equals its successor (substring) QUANTUM Represents the Quantum= attribute of the dataloc form. This value defines what constitutes a quantum in the data. Valid values are: NORM Normalized text: all characters except record start (RS), record end (RE), and separation characters (SEPCHAR), normally space and tab. WORD Word tokens: all name characters. NAME SGML name: NAME constructed according to ISO 8879. SINT Signed integer: digit string, optionally preceded by a hyphen or plus. DATE UTC date: valid date in UTC yyy-mm-dd format. TIME UTC time: valid time in UTC hh:mm:ss.decimal format. UTC UTC date and time: pairs of DATE and TIME tokens, DATE first. STR The data quantum is a bit combination ("character") and the addressable range is viewed as a string. There is no filtering or normalization. Addressing is always in terms of complete bit combinations. NODE NODE LIST The node or nodes to be compared to each other using the specified comparison. Purpose Use Compare() to compare the members of a node list to each other using a comparison. Comparisons are done in a way appropriate for the quantum. Examples This simple example uses compare to confirm that the node list returned by the query in the example for assign() is really made up only of P elements. In this example, the HyQ query is contained within a made-up element called TrueOrFalse. For the purpose of this example, assume that the purpose of the TrueOrFalse element is to contain a query that will return either TRUE or FALSE and that the result of the query will be taken as the data of the TrueOrFalse element. Note the Notation= attribute indicating that the data contained by the TrueOrFalse element is a HyQ query. <TrueorFalse notation=HyQ> | and( | assign(nlref(ElderSiblings) relloc(DOMTREE oo(an-element) esib (1 -1))) | compare(EQ select(ElderSiblings EQ(proploc(CAND GI) "P")) | ) <TrueorFalse> ------------------------------------------------------------------------------ create() Create a node list Syntax <- -----------------< >>---.--------.-(---.-| Node |------.---)--------------------------->< '-create-' '-| Node List |-' NODE Node List The node or nodes making up the node list. Purpose Use the Create() function to create a node list, such as a list of literal values. The function name can be omitted. This means that any group of valid nodes will be interpreted as a node list when surrounded by parentheses any place a node list is valid. Examples In this simple example, the create() function is used to create two lists of literals for the diff() function. The second node list demonstrates how the create name can be omitted: <HyQ> diff(CREATE("id-a" "id-b" "id-c") ("id-a" "id-c" "id-d")) </HyQ> ------------------------------------------------------------------------------ dataloc() Select data from nodes Syntax .- STR--. .- NOCATSRC-. >>--dataloc(--| Node List |--+-------+--+-----------+----------------> |- NORM-| '- CATSRC---' |- WORD-| |- NAME-| |- SINT-| |- DATE-| |- TIME-| '- UTC--' .- NOCATRES-. .- ERROR--. >--+-----------+--.-----------------------.--+---------+--)--------->< '- CATRES---' | <-----------------< | |- WRAP---| '----| Marker Pair |----' |- TRUNC--| '- IGNORE-' MARKER PAIR: |-- (signed_non-zero_integer signed_non-zero_integer)----------------| NODE LIST The list of nodes from which data will be selected. QUANTUM Represents the Quantum= attribute of the dataloc form. This value defines what constitutes a quantum in the data. Valid values are: NORM Normalized text: all characters except record start (RS), record end (RE), and separation characters (SEPCHAR), normally space and tab. WORD Word tokens: all name characters. NAME SGML name: NAME constructed according to ISO 8879. SINT Signed integer: digit string, optionally preceded by a hyphen or plus. DATE UTC date: valid date in UTC yyy-mm-dd format. TIME UTC time: valid time in UTC hh:mm:ss.decimal format. UTC UTC date and time: pairs of DATE and TIME tokens, DATE first. STR The data quantum is a bit combination ("character") and the addressable range is viewed as a string. There is no filtering or normalization. Addressing is always in terms of complete bit combinations. CATSRC NOCATSRC Concatenate source. Concatenates the objects of a multiple location source into a single object before applying the dimension list to it. The parsing context must be the same for all of the objects. Nocatsrc is the default. CATRES NOCATRES Determines whether or not the result of the query should be concatenated. MARKER PAIR One or more dimension marker pairs defining the location within the objects being located. OVERRUN Overrun handling specification as defined in 10744 7.1.2.1. The overrun handling determines what action to take in the event that a dimension reference exceeds the size of the addressable range. Valid values are: ERROR Treat the overrun as an error condition. WRAP Wrap around the range modulo the length of the range. TRUNC Truncate either to the first or last quantum of the range. If either marker is before the first quantum, it is treated as the first quantum. If either marker is after the last quantum, it is treated as the last quantum. IGNORE Treat the dimension as though it had not been specified. This may result in an error in some circumstances. Purpose Use dataloc() to locate data directly, rather than indirectly using some abstraction of the data (such as node lists. See the entry for listloc() for a discussion of the difference between dataloc() and | listloc()). For example, you could use dataloc() to locate data | within an ASCII text file or a string words within an SGML element. (See 10744 8.4.1 for more information using data locations). Examples | This example locates a segment of sound data within a sound object. | The returned sound data is used as the content of the Audio element | for presentation purposes: | <Audio notation=HyQ> | dataloc(oo(asound) (10 1000) | </Audio> | The object-of function is used to define the location source for the | query. The value 'asound' in this example is the ID of another | element that refers to the actual audio data entity. The marker pair | then locates that part of the sound starting at 10 and extending for | 1000 quanta. This example uses the defaults for the quantum, catsrc, catres, and overrun attributes. This next example uses dataloc to address into the content of an element. The quantum value 'WORD' is used, meaning that the data will be divided into word quanta at each non-name character. The target element is: <phrase id=cats>Charles' and Linda's Abyssinians</phrase> The query to find the second and third words is: <NewPhrase notation=hyq> dataloc(oo(cats) word (2 2)) </NewPhrase> The object-of function makes the element with the ID 'cats' the location source. The marker pair '2 2' locates the second and third words (start at quantum 2 and extend for 2 quanta). The resolved | content of the NewPhrase element is thus 'and Linda'. ------------------------------------------------------------------------------ diff() Difference between nodelists Syntax <- -------------< >>--diff(---| Node List |---)--------------------------------------->< NODE LIST The node lists to be compared. The diff is applied by taking the diff of the first two node lists, then taking the diff the result with the next node list, and so on. Purpose Use Diff() to find the differences between two node lists. Examples In this simple example, two lists of literals are compared to find the differences. In this example, the literals are element IDs. <HyQ> diff(("id-a" "id-b" "id-c") ("id-a" "id-c" "id-d")) </HyQ> | The result of the diff is 'id-b id-d' ------------------------------------------------------------------------------ forall() Do all nodes meet assertion? Syntax >>--forall(-| Node List |- -| query() |-)--------------------------->< NODE LIST The node list to apply the query against. QUERY() The query function that will be applied to each node in the node list. Purpose Forall() returns TRUE if all nodes in a node list satisfy a query. Examples In this example, a proploc query is used to determine whether or not all elements in the domain have an ID attribute value: forall(DOMTREE query(proploc(DOMROOT ATTVAL[ID])) The proploc() function returns the value of the ID attribute for the candidate node. Because the proploc() function occurs where an assertion is expected, it will resolve to TRUE if the property value is not empty, FALSE if it is). The forall() function will return TRUE if all the candidate nodes get a TRUE result from the query. ------------------------------------------------------------------------------ hylex() Define a HyLex expression Syntax .- NORM--. >>--hylex((HyLex specification)--+--------+--.-------------------.---> '- UNORM-' '- OO(lexord_idref)-' >--)---------------------------------------------------------------->< HyLex Specification A pattern specification in the HyLex notation. HyLex is similar to Unix regular expressions. See 10744 Annex A.1 for more information about HyLex. NORM UNORM Indicates whether or not the target strings are normalized as for dataloc with the NORM option. The default is normalization. OO(lexord_idref) Refers to a lexical ordering (lexord) element that defines the lexical ordering to be used for satisfying the HyLex pattern. The default is to use the ordering of the active character set. Purpose Use HyLex() to define a HyLex pattern for use within a match() function. Examples This example uses HyLex within match() to see the target elements contain a US zip code: <HyQ> select(DOMTREE match(CAND HYLEX((digit, digit, digit, digit, digit, ("-",digit, digit, digit, digit)?))) </HyQ> ------------------------------------------------------------------------------ inter() Intersection of node lists Syntax <- -------------< >>--inter(---| Node List |---)-------------------------------------->< NODE LISTS The node lists to take the intersection of. The node list returned contains the nodes common to all node lists specified. Purpose Use inter() to find common members in two node lists. This is useful for combining different queries. For example, you might do one query that returns a list of nodes containing a certain string and another that returns a list matching a certain property. You can use inter() to find the nodes common to both queries, thus finding the nodes with the property that contain the string. Examples This query creates two node lists and then finds the intersection of them: <HyQ> assign(PhraseList select(DOMTREE UseQ(HasGI "phrase"))) assign(ContainsAIX select(DOMTREE match(CAND "AIX"))) inter(nlref(PhraseList) nlref(ContainsAIX))  </HyQ> ------------------------------------------------------------------------------ listloc() Pick nodes from list by position Syntax >>--listloc(--| Node List |--.-----------------------.---------------> | <-----------------< | '----| Marker Pair |----' .- ERROR--. .- NOSET-. >--+---------+--+--------+--)--------------------------------------->< |- WRAP---| '- SET---' |- TRUNC--| '- IGNORE-' MARKER PAIR: |-- (signed_non-zero_integer signed_non-zero_integer)----------------| NODE LIST The node list from which nodes will be returned according to the marker specifications. MARKER PAIRS One or more pairs of axis markers locating the nodes to be returned. OVERRUN Overrun handling specification as defined in 10744 7.1.2.1. The overrun handling determines what action to take in the event that a dimension reference exceeds the size of the addressable range. Valid values are: ERROR Treat the overrun as an error condition. WRAP Wrap around the range modulo the length of the range. TRUNC Truncate either to the first or last quantum of the range. If either marker is before the first quantum, it is treated as the first quantum. If either marker is after the last quantum, it is treated as the last quantum. IGNORE Treat the dimension as though it had not been specified. This may result in an error in some circumstances. SET NOSET Determines whether or not a multiple location is treated as a set by removing duplicates. The default is NOSET. Purpose Use listloc() to locate nodes within a node list. Listloc() is essentially the same as a dataloc, but is restricted to a single | dimension as node lists are always one dimensional. Listloc() is also | distinquished from dataloc() by the type of quanta addressed. | Dataloc() addresses bit combinations or tokens, while listloc() | address nodes. Nodes are, by their nature, an abstraction of a given | data notation, thus a node list is always the result of applying some | sort of abstracting processing against data (e.g., parsing it with an | SGML parser to find the element "nodes"). Note that any data type can | be abstracted into a node list by applying some sort of parser to it. | For example, raw video data could be addressed using dataloc, or it | could be abstracted into a node list of "frames" by first applying a | program that decoded the video data into frame chunks. | Another way to think of the difference between listloc() and dataloc() | is that while dataloc() operates on and returns the raw data, | listloc() operates on and returns sets of pointers to data. Examples This example uses dataloc to return the content of a node as a node list of words and then uses listloc to return the fourth through sixth nodes in the resulting list: <HyQ> listloc(dataloc(oo(an-element) word (1 -1)) (4 3)) </HyQ> | The example shows how dataloc() abstracts the raw data (words) into | nodes, which can then be addressed as a node list by listloc(). ------------------------------------------------------------------------------ match() Pick nodes by pattern match of content Syntax >>--match(--.-| Node |------.--.- -| hylex() |----------------.------> '-| Node List |-' |- qualified_lexical_type_name-| '- literal---------------------' .- ISCIEC--. >--.-------------.--+----------+--.------------------------.--)----->< '- OO(lexord)-' |- SODEOD--| '- minhits-.----------.--' |- SODIEC--| '- maxhits-' |- ISCEOD--| '- INMODEL-' NODE NODE LIST The node or node list against which the match is applied. When a node list is specified, the match is applied against each node in the list. HYLEX() qualified_lexical_type_name LITERAL The pattern to be matched against. Can be specified with the HyLex() function, by giving the name of a qualified lexical type, or by specifying a string literal. OO(lexord_idref) Refers to a lexical ordering (lexord) element that defines the lexical ordering to be used for satisfying the HyLex pattern. The default is to use the ordering of the active character set. BOUNDARY CONSTRAINT These keywords define the boundary constraints for the hits as follows: ISCIEC Ignore starting characters, ignore ending characters. Indicates that the hit can be anywhere within the match domain. This is the default. SODEOD Match start of domain and end of domain. The hit must start at the start of the domain and end at the end of it. For a literal string, the hit must match the domain. For lexical types or HyLex patterns, the entire domain must satisfy the lexical constraints. SODIEC Match start of domain, ignore ending characters. The hit must match the start of the domain. ISCEOD Ignore starting characters, match end of domain. INMODEL Indicates that the boundary constraints are defined in the HyLex lexical model or the model for the referenced lexical type. minhits maxhits Defines the hit range for the match, in other words the minimum and, optionally, maximum number of hits needed to satisfy the match. Purpose Use match to do patterning matching within a query. The pattern matching mechanism can be one of the following: o Simple string match, done by specifying a string literal, and optionally, the boundary constraints. o HyLex pattern matching using a HyLex lexical model as defined in 10744 Annex A.1., either by specifying the lexical model directly with a HyLex() function or by defining a lexical type elsewhere and specifying the lexical type name. o A non-HyTime-defined pattern matching method using a pre-defined lexical type name defined using an application-defined notation (for example, grep regular expressions could be defined as a notaton and used via defined lexical type names). Examples This example uses match() with a literal string and a boundary constraint to find all phrase elements that start with the string 'AIX'. <HyQ> match(UseQ(HasGI "phrase") "AIX" SODIEC) </HyQ> ------------------------------------------------------------------------------ nl Nodelist-creating functions Syntax NL: |--.-DOMTREE------.--------------------------------------------------| |-DOMROOT------| |-| assign() |-| |-| nlref() |--| |-| nlops() |--| |-| nldefs() |-| |-| oo() |-----| '-| query() |--' Purpose Use nodelist-creating functions wherever a node list is valid. The special keyword DOMTREE refers to all nodes rooted to the domain root. The special keyword DOMROOT refers to the node list that is the root of the domain. ------------------------------------------------------------------------------ nldefs Nodelist-defining functions Syntax NL DEFS: |--.-| proploc() |-.-------------------------------------------------| |-| treeloc() |-| |-| pathloc() |-| |-| listloc() |-| |-| dataloc() |-| '-| relloc() |--' Purpose Nodelist-defining functions return a node list consisting of nodes selected from the input node list. ------------------------------------------------------------------------------ nlops Nodelist-manipulating functions Syntax NL OPS: |--.-| select() |-.--------------------------------------------------| |-| create() |-| |-| union() |--| |-| inter() |--| '-| diff() |---' Purpose Node-list manipulating functions apply another function against the members of the input node list, returning a new node list containing those nodes from the input that satisfied the function. ------------------------------------------------------------------------------ nlref() Resolves name to nodelist Syntax >>--nlref(nodelist_name)-------------------------------------------->< nodelist_name The name of a node list previously created in the same query using the assign() function. Purpose Lets you use a node list by reference. Examples In this example, assign() used to create two node list names, which are then used by reference in the inter() function. <HyQ> assign(PhraseList select(DOMTREE UseQ(HasGI "phrase"))) assign(ContainsAIX select(DOMTREE match(CAND "AIX"))) inter(NLREF(PHRASELIST) nlref(ContainsAIX))  </HyQ> ------------------------------------------------------------------------------ Node Node specification methods Syntax NODE: |--.-"literal data"---------.----------------------------------------| |-CAND-------------------| |-| Argument Reference |-| |-| oo() |---------------| '-| count() |------------' "literal data" A node list of literals, such as IDs or other tokens. CAND The current candidate node within the context of a select() function. ARGUMENT REFERENCE Refers to a variable argument, e.g., %1, %2. OO() Object-of function. Returns the node list of nodes corresponding the element or entity referred to in the body of oo(). When unified entity and ID name spaces are not being used, an entity can be referred by using a named location address that refers to an entity. COUNT() Returns a single integer value representing the number of quanta in an addressable range. Purpose Any of these node-specification methods are valid wherever a single node or node list is valid. ------------------------------------------------------------------------------ not() Test Boolean NOT Syntax >>--not(-| Assertion |-)-------------------------------------------->< ASSERTION Any of the assertion methods defined under Assertion. All assertion methods return either TRUE or FALSE. Purpose Returns TRUE if the assertion is FALSE, returns FALSE if the assertion is TRUE. Examples This simple example always returns FALSE: <HyQ> not(assert(TRUE)) </HyQ> ------------------------------------------------------------------------------ oo() Resolves IDREF to its object Syntax >>--oo(element_ID)-------------------------------------------------->< element_ID Returns as a node the element or entity referred to by the element_ID value. When unified ID and entity name spaces are not used, oo() can refer to an entity by referring to a named location address (nameloc) that then refers to an entity. Purpose Use object-of to refer directly to elements for the purpose of defining the domain of a query. When the ID and entity name space is unified, object-of can refer directly to a declared entity. When the name spaces are not unified, entities can be refered to by using a named location address (nameloc) element to refer to the entity and then using object-of to refer to the nameloc element. Examples This example uses oo() to get an element to be the source for a dataloc() query that returns the content of the object: <HyQ> dataloc(OO(AN-ELEMENT) word (1 -1)) </HyQ> The next example shows how to refer to an entity by using nameloc to create a location ladder that refers to an entity. The dataloc() then addresses a portion of the graphic:   <!ENTITY an-entity SYSTEM "filename.ext" NDATA graphic > . . .  <nameloc id=entity-reference><nmlist entity>an-entity</nameloc> <HyQ> dataloc(OO(ENTITY-REFERENCE) str (10 256)(35 1556) </HyQ> ------------------------------------------------------------------------------ or() Test Boolean OR Syntax <---------------< >>--or(---| Assertion |---)----------------------------------------->< ASSERTION Any of the assertion methods defined under Assertion. All assertion methods return either TRUE or FALSE. Purpose OR returns TRUE if any of the assertions are TRUE, and FALSE if all of them are false: Examples This example returns true if either attribute value matches the specified values: <HyQ> select(DOMTREE OR(EQ(proploc(CAND ATTVAL[HWPLATFORM]) "PS/2") EQ(proploc(CAND ATTVAL[SWPLATFORM]) "AIX"))) </HyQ> ------------------------------------------------------------------------------ ordered() Tests if nodes are properly ordered Syntax | >>--ordered(--| Node List |--.-----------.--)----------------------->< |-OVERLAP---| '-NOOVERLAP-' OVERLAP NOOVERLAP Indicates whether or not the nodes can overlap. Purpose Returns TRUE if all the nodes have the same additional property source (apropsrc, see 10744 8.5.1: Property location address) and are ordered within it. The additional property source is the common container for all the nodes. Examples The following query returns TRUE: <HyQ> | ordered(('1' '2' '3' '4')) </HyQ> ------------------------------------------------------------------------------ pathloc() Pick nodes from tree by paths Syntax >>--pathloc(--| Node List |--.-----------------------.---------------> | <-----------------< | '----| Marker Pair |----' .- NTREECOM-. .- ERROR--. .- NOTSET-. |- TREECOM--| >--+---------+--+---------+--'-----------'--)----------------------->< |- WRAP---| '- SET----' |- TRUNC--| '- IGNORE-' NODE LIST The tree being addressed. MARKER PAIRS Two or more sets of marker pairs locating the path within the tree. OVERRUN Overrun handling specification as defined in 10744 7.1.2.1. The overrun handling determines what action to take in the event that a dimension reference exceeds the size of the addressable range. Valid values are: ERROR Treat the overrun as an error condition. WRAP Wrap around the range modulo the length of the range. TRUNC Truncate either to the first or last quantum of the range. If either marker is before the first quantum, it is treated as the first quantum. If either marker is after the last quantum, it is treated as the last quantum. IGNORE Treat the dimension as though it had not been specified. This may result in an error in some circumstances. SET NOTSET Determines whether or not the result node list is treated as a set by removing duplicates. TREECOM NTREECOM Determines whether or not multiple source trees are combined. The default is no combination. Purpose Pathloc locates into a tree as though it were a matrix where each column consists of each node from the root to one leaf. Examples This query locates the path from the root to the second leaf of the tree: <HyQ> pathloc(DOMTREE (2 1 1 -1)) </HyQ> By using the SET parameter, you can remove the duplicates created by locating more than one path: <HyQ> pathloc(DOMTREE (2 2 2 4) SET) </HyQ> ------------------------------------------------------------------------------ proploc() Returns value of a property Syntax >>--proploc(--.-| Node |------.-- qualified_property_name------------> '-| Node List |-' .- SEVERAL-. .- SOLESRC--. .- IGNORE-. >--+----------+--+-----------+--+---------+--)---------------------->< '- JOINT---' '- APROPSRC-' |- ERROR--| '- EMPTY--' NODE NODE LIST The node or node list from which property values are to be retrieved. qualified_property_name The name of the property to be retrieved. For SGML attributes, this is simply the name of the attribute. The keyword 'GI' returns the generic identifier of the element. Other properties can be defined using HyTime property definitions (see 10744 6.7 Property sets and A.2 HyTime Property definition). JOINT SEVERAL Determines whether or not the property applies to to all the nodes in the source node list jointly or to each node individually. The default is SEVERAL SOLESRC APROPSRC Indicates whether or not to consider an additional property source if the property is not applicable to the defined source. IGNORE EMPTY ERROR Determines the behavior in the case where the property is not a property of the source node. When IGNORE is specified, the proploc is treated as though it didn't exist. When EMPTY is specified, an empty node is returned. When ERROR is specified it is an error condition. Purpose Use proploc() to get the value of various properties of nodes, such as the values of attributes of SGML elements. The value is returned as a string literal. | Examples This query returns the value of the GI property of the source element: <HyQ> proploc(oo(an-element) GI) </HyQ> ------------------------------------------------------------------------------ query() specifies a query with args Syntax >>--query(--| Query Body |-------------------------------------------> >--.---------------------------------------.--)--------------------->< '-| Query Domain |--| Query Arguments |-' QUERY BODY: |--| Node List |-----------------------------------------------------| QUERY DOMAIN: .-DOMROOT-------. |--+---------------+-------------------------------------------------| '-| Node List |-' QUERY ARGUMENTS: <----------< |----| Node |--------------------------------------------------------| QUERY BODY The query itself, defined using normal HyQ primitives. QUERY DOMAIN The domain against which the query is applied. QUERY ARGUMENTS Arguments to be passed to the query body as though specified on the args= attribute of the HyQ element. Purpose Query() lets you define a query with replaceable arguments and then call it directly, rather than indirectly via the UseQ function. The difference between query() and UseQ() is that with UseQ() the function body is refered to indirectly and may be defined elsewhere, while with query(), the function body is defined within the query() function itself. Examples This example defines a simple query with one argument and then uses query() to apply it against the specified query domain, returning a node list containing the value of the Security= attribute for each node in DOMTREE: query(proploc(%1 ATTVAL[SECURITY]) DOMTREE) ------------------------------------------------------------------------------ relloc() Pick nodes from tree by relatives Syntax .- PARENT---. >>--relloc(--| Node List |-- --.-| Node |------.--+-----------+------> '-| Node List |-' |- ANC------| |- ESIB-----| |- YSIB-----| |- DES------| '- CHILDREN-' .- ERROR--. .- NOTSET-. >--.-----------------------.--+---------+--+---------+--)----------->< | <-----------------< | |- WRAP---| '- SET----' '----| Marker Pair |----' |- TRUNC--| '- IGNORE-' | NODE LIST | The node or node list whose relatives are to be located. | NODE | NODE LIST | The root of tree within against which the relloc() is performed, | normally, DOMROOT. RELATION: ANC Ancestors of source. ESIB Elder siblings of source. YSIB Younger siblings of source. DES Descendants of source. Addressed as for pathloc(). PARENT Parent of source. Equivalent of ANC with a dimlist of (-1 1). Actual dimlist must be empty. CHILDREN Children of source. Equivalent of DES with a dimlist of (1 -1 2 1). Actual dimlist must be empty. MARKER PAIRS Sets of axis markers locating elements within the set of elements identified by the relationship keyword. Cannot be specified for PARENT or CHILDREN relationships. OVERRUN Overrun handling specification as defined in 10744 7.1.2.1. The overrun handling determines what action to take in the event that a dimension reference exceeds the size of the addressable range. Valid values are: ERROR Treat the overrun as an error condition. WRAP Wrap around the range modulo the length of the range. TRUNC Truncate either to the first or last quantum of the range. If either marker is before the first quantum, it is treated as the first quantum. If either marker is after the last quantum, it is treated as the last quantum. IGNORE Treat the dimension as though it had not been specified. This may result in an error in some circumstances. SET NOTSET Determines whether or not the result node list is treated as a set by removing duplicates. Purpose Use relloc() to construct queries about nodes based on their genealogical relationships to other nodes. Examples The following query locates the second path from the source node to the the bottom of the tree: <HyQ> | relloc(oo(an-element) DOMROOT DES (2 1 1 -1)) </HyQ> ------------------------------------------------------------------------------ select() Select nodes from list by assertion Syntax >>--select(--| Node List |-- --| Assertion |--)--------------------->< NODE LIST The list of nodes from which the result node list will be selected. ASSERTION Any of the assertion functions. The assertion is applied to each node in the source node list, and any node for which the assertion evaluates to TRUE will be returned in the result node list. Purpose Use select() to select nodes out of a node list. Within the context of select(), the keyword CAND refers to the current candidate node in source node list. When select() is nested within a select, CAND refers to nodes in the node list of the innermost select that contains the query using CAND. If you need to use the value of an outer CAND within the body of a nested select, you can use assign() to assign CAND to a symbolic name and then use nlref() within the nested select to refer to the assigned name. Examples This example selects from the domain tree all nodes whose GI is equal to the value "partnum": <HyQ> select(DOMTREE EQ(proploc(CAND GI) "partnum")) </HyQ> In this example, assign() is used to capture the value of CAND for use in a nested select. The query compares the value of the security= attribute of containing Section elements with the security= value of footnotes within the Section: <HyQ> Select(DOMTREE and(Eq(Proploc(CAND GI) "SECTION") ASSIGN(CURSECTION CAND) Select(PATHLOC((CAND) 1 -1 2 -1)' and(Eq(Proploc(CAND GI) "FOOTNOTE") Le(Proploc(CAND ATTVAL[SECURITY]) Proploc(NLREF(CURSECTION) ATTVAL[SECURITY]) ) ) ) </HyQ> ------------------------------------------------------------------------------ treeloc() Pick nodes from tree by position Syntax <------------------------< >>--treeloc(--| Node List |--- signed_non-zero_integer---------------> .- NTREECOM-. .- ERROR--. .- NOTSET-. |- TREECOM--| >--+---------+--+---------+--'-----------'--)----------------------->< |- WRAP---| '- SET----' |- TRUNC--| '- IGNORE-' NODE LIST The root node(s) of the tree to which the treeloc() applies. SIGNED_NON-ZERO_INTEGERS The number of each ancestor node at each level of the tree. Each number is essentially a listloc of the form (x 1), locating a single node in the node list of children of the previous node. OVERRUN Overrun handling specification as defined in 10744 7.1.2.1. The overrun handling determines what action to take in the event that a dimension reference exceeds the size of the addressable range. Valid values are: ERROR Treat the overrun as an error condition. WRAP Wrap around the range modulo the length of the range. TRUNC Truncate either to the first or last quantum of the range. If either marker is before the first quantum, it is treated as the first quantum. If either marker is after the last quantum, it is treated as the last quantum. IGNORE Treat the dimension as though it had not been specified. This may result in an error in some circumstances. SET NOTSET Determines whether or not the result node list is treated as a set by removing duplicates. TREECOM NTREECOM Determines whether or not multiple source trees are combined. The default is no combination. Purpose Use treeloc() to locate single nodes within a tree. Treeloc() is a very compact way to locate nodes within trees. For example, using the sample tree shown under "Nodelist and Tree Addressing" on page i, the tree location (3 2) locates the node labeled "I", while the tree location (1 2 1) locates the node labeled "J". Examples The following example uses relloc() to locate the children of DOMROOT and then uses treeloc() to find the first child of the second child of each child of DOMROOT: <HyQ> treeloc(relloc(DOMROOT CHILDREN) 2 1 NTREECOM) </HyQ> The NTREECOM keyword states explicitly that for the node list returned by relloc(), each node should be treated as the root of a separate tree. ------------------------------------------------------------------------------ union() Union of Node Lists Syntax <---------------< >>--union(---| Node List |---)-------------------------------------->< NODE LISTS The node lists to be combined. Purpose Takes two or more node lists and combines them into a single node list, removing any duplicates. Examples This example uses two proploc() functions to create two node lists of elements with specific GIs, and then uses union() to combine the two lists into one: <HyQ> union(select(DOMTREE eq(proploc(CAND GI) "CAUTION")) select(DOMTREE eq(proploc(CAND GI) "WARNING"))) </HyQ> ------------------------------------------------------------------------------ UseQ() Indirect query Syntax >>--useq(--function_name---------------------------------------------> >--.---------------------------------------.--)--------------------->< '-| Query Domain |--| Query Arguments |-' QUERY DOMAIN: .-DOMROOT-------. |--+---------------+-------------------------------------------------| '-| Node List |-' QUERY ARGUMENTS: <----------< |----| Node |--------------------------------------------------------| function-name The name of a HyQ function defined elsewhere using the FN= attribute of the HyQ element. QUERY DOMAIN The domain against which the named query is applied. The default is DOMROOT. QUERY ARGUMENTS A node or node list containing the arguments to the named query. Purpose Use UseQ() to use pre-defined functions. Examples This example defines a new function, called Has_Attribute_Value, which takes an attribute name and value and returns TRUE if the node's attribute has the value. This function is then used in a subsequent query. <HyQ fn="Has_Attribute_Value">  EQ(proploc(%1 %2) %3) </HyQ>  <HyQ> select(DOMTREE USEQ(Has_Attribute_Value CAND ATTVAL[SECURITY] "IUO")) </HyQ> Footnotes: | (1) The simplest application of multi-dimensional address is through of use of | finite coordinate space location elements (fcsloc), which provide a | mechanism for imposing a finite coordinate space onto an object for the | purpose of then locating areas within the object. For example, one way to | define hot spots within bitmap images would be to use fcsloc elements to | define rectangular regions within the image. | The other application of multi-dimentional addressing is to define the | location of objects (called events) within a finite coordinate space using | an indirection method called an event schedule The purpose of an event | schedule is to associate objects with locations within a coordinate space of | one or more dimensions. The subject of event schedules and finite | coordinate spaces is beyond the scope of this document. For now, just | remember that an extent list contains one set of dimension specifications (a | dimlist) for each axis in the finite coordinate space. (2) SGML documents can also be represented as one-dimensional coordinate spaces with the quanta representing SGML elements in the order they are encountered | (3) See section 6.7 Property Sets for the definition of HyTime's property set | elements (4) Note that the GI property is one of the standard properties and so the property set name specification can be omitted, as it is in this example